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^ : Abstract 

An upgraded version of the package [BCVEGPY2.0: Chao-Hsi Chang, Jian-Xiong Wang and 
Xing-Gang Wu, Comput. Phys. Commun. 174 (2006) 241-251] is presented, which works under 
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users may simulate the i?c-events in various experimental environments very conveniently. It 
has been rearranged for better modularity and code reusability (less dependency among various 



Cn I LINUX system and is named as BCVEGPY2.1. Using this version with a GNU C compiler, 
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\^ ! modules) than BCVEGPY2.0 has. Furthermore, in the upgraded version a special and convenient 

executable-file run as default is available according to one's wish, i.e., the file is obtained in the 

way that the GNU command make compiles the codes requested by precise purpose with the help 
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O , of a master makefile in the main code directory. Finally, this paper may also be considered as an 

erratum of the original BCVEGPY2.0, i.e., here the errors (typo mainly) in BCVEGPY2.0 have 

•r-t . 

/\f • been corrected. 
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NEW VERSION PROGRAM (BCVEGPY2.1) SUMMARY 

Title of program : BCVEGPY2.1 

Program obtained from : CPC Program Library or the Institute of Theoretical Physics, 
Chinese Academy of Sciences, Beijing, P.R. China: www.itp.ac.cn/~zhangzx/bcvegpy2.1. 

Reference to original program : BCVEGPY2.0 

Reference in CPC : Comput. Phys. Commun. 174, 241(2006) 

Does the new version supersede the old program: No 

Computer : Any LINUX based on PC with FORTRAN 77 or FORTRAN 90 and GNU C 
compiler as well. 

Operating systems : LINUX. 

Programming language used : FORTRAN 77/90. 

Memory required to execute with typical data : About 2.0 MB. 

No. of bytes in distributed program, (including PYTHIA6.2) : About 1.2 MB. 

Distribution format : .tar.gz . 

Nature of physical problem : Hadronic production of Be meson itself and its excited states. 

Method of solution : The code with option can generate weighted and un-weighted events. 
An interface to PYTHIA is provided to meet the needs of jets hadronization in the 
production. 



Restrictions on the complexity of the problem : The hadronic production of (c6)-quarkoniuin 
in S-wave and P-wave states via the mechanism of gluon-gluon fusion are given by the 
so-called 'complete calculation' approach. 

Reasons for new version : Responding to the feedback from users, we rearrange the 
program in a convenient way and then it can be easily adopted by the users to do the 
simulations according to their own experimental environment (e.g. detector acceptances 
and experimental cuts). We have paid many efforts to rearrange the program into several 
modules with less dependency among the modules, the main program is slimmed down and 
all the further actions are decoupled from the main program and can be easily called for 
various purposes. 

Typical running time : The typical running time is machine and user-parameters dependent. 
Typically, for production of the S-wave (c6)-quarkonium, when IDWTUP=1, it takes about 
20 hour on a 1.8 GHz Intel P4-processor machine to generate 1000 events; however, when 
IDWTUP=3, to generate 10^ events it takes about 40 minutes only. Of the production, the 
time for the P-wave (c6)-quarkonium will take almost two times longer than that for its 
S'-wave quarkonium. 

Keywords : Event generator; Hadronic production; Be meson. 

Summary of the changes (improvements) : 

(1) The structure and organization of the program have been changed a lot. The new version 
package BCVEGPY2.1 has been divided into several modules with less cross communication 
among the modules (some old version source files are divided into several parts for this 
purpose). The main program is slimmed down and all the further actions are decoupled 
from the main program so that they can be easily called for various applications. All of 
the Fortran codes are organized in the main code directory named as bcvegpy2.1, which 
contains the main program, all of its prerequisite files and subsidiary 'folders' (subdirectory 
to the main code directory). The method for setting the parameter is the same as that of 
the previous versions [ll, |2], i-e. the parameters are set in a file named parameter. F. Each 



subsidiary 'folders' contains the necessary files to complete specific tasks accordingly. There 
are in total seven modules/'folders' in the program: 

• The module generate: it is the key module, which contains the files for generating 
the Be events. There are seven source files in this 'folder': evntinit.F, colorfiow.F, 
genevnt.F, py6208.F (a nickname of PYTHIA6.208 ^), totfun.F, outerpdf.F and init- 
mixgrade.F. The function of the module generate is to set the initialize conditions for 
event simulation; to establish a connection with PYTHIA 3| ; to establish a connection 
to the parton distribution functions (PDFs) that are not included in PYTHIA accord- 
ing to specific need; to record the color flow information of the generated B^ events 
and may provide it according to one's need; to calculate the kernel for phase space 
integration with the help of swave module and pwave module; to do the phase space 
integration with the help of phase module. A useful trick for generating the mixed 
type of Be events is suggested (three types of mixed events are provided in the gen- 
erator [2l|, e.g. by setting the parameter IMIXTYPE=2, one can generate the mixed 
events for the two color-singlet (c6)-quarkonium states (c6)i(^5'o) and (c6)i(^5'i)). The 
file initmixgrade.F is used to initialize the importance sampling function for Monte 
Carlo simulation, i.e., either by using the importance sampling function given by the 
current VEGAS running j^ or by using the existing importance sampling function 
recorded in an existing grade file in data subdirectory that has already been generated 
by earlier VEGAS running. Once the importance sampling function has been obtained 
by VEGAS, it is recorded in a grade file (with suffix .grid) automatically, and can be 
conveniently used (by initmixgrade.F) for later usage without running VEGAS again. 
Some more detail on this point will be shown in the following item (2). 

• The module phase: it contains the files for generating the allowed phase-space point 
and for generating an importance sampling function with VEGAS program jjl. It 
contains three source files: phase_gen.F, phase_point.F and vegas.F. 

• The module swave: it contains the files for calculating the square of the amplitudes for 
producing the four color-singlet and color-octet (c6)-quarkonium in S-wave: {cb)i{^So), 
{cb)i(^Si), (c6)8(^5'o) and {cb)s(^Si), where the subscripts 1 and 8 stand for color- 
singlet and color-octet accordingly. Note that in fact the configurations (c6)8(^>S'o) 
and {cb)s{^Si) play comparatively an important role only for the production of the 
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ptiase/ generating aiiowed phase space 

generate/ generating events 

system/ recording running information 
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all the obtained data files are put he 



FIG. 1: The schematic structure for the new version of BCVEGPY. 

P-wave excited B^ states as shown in Ref.p. It contains five source files: s_bound.F, 
s_comnion.F, s_foursets.F, s_free.F and s_sanip.F. 

• The module pwave: it contains the files for calculating the square of the ampli- 
tudes for producing the four color-singlet (c6)-quarkonium in P-wave: (c6)i(^Pi) and 
(c6)i(^Pj) (J = 1, 2, 3). It contains six source files: pJorentz.F, plplamp.F, pjOamp.F, 
pjlamp.F, pj2amp.F and p_samp.F. 

• The module pybook: it contains the files for initializing the subroutine PYBOOK of 
PYTHIA to record the events. The user may conveniently switch off this module in 
the main program to use his/her own way to record the data. It contains five source 
files: pybookinit.F, uphistrange.F, uppydump.F, uppyfact.F and uppyfill.F. 

• The module setparameter: it contains the files for inner use of the parameters 
(mainly generates some short notations for the parameters) that have been set in 
parameter. F. It has only two source files: simparameter.F and uperror.F, where up- 
error.F lists some typical error messages for the cases when the input parameters are 
out of allowed (reasonable) range. 

• The module system: it contains files to open or close the record files and to print out 
certain running messages at the intermediate steps according to need, which may tell 
the users at what step the program is running. It contains six source files: upopenfile.F, 
uplogo.F, vegaslogo.F, updatafile.F, upclosegradefile.F and upclosepyfile.F. 

Each module is equipped with its own makefile that will be used to make a library 
of the same name, e.g. the makefile in the 'folder' swave/ will be used by the GNU 
command make to generate a library swave. a. These sub- makefiles are orchestrated by a 



master makefile in the main code directory. Libraries required for tlie main program are 
listed in the LIBS variable of the master makefile and built automatically by invoking the 
sub-makefiles: 

LIBS = generate. a swave.a pwave.a phase. a setparameter.a system.a pybook.a 

By running the make command under the directory of the main codes, the master 
makefile is called automatically and the requested executable-file run is obtained. There- 
fore, the program acquires good modularity and code reusability, and the users can easily 
make the BCVEGPY generator to suit their experimental simulation environment. Namely, 
to connect this generator with his/her own generator package such as ATHENA (used by 
ATLAS group). Gauss (used by LHCb group) and SIMUB (used by CMS group) ^ only a 
few pieces of the program need to be changed. By doing this way, the time for compiling 
the Fortran source files can be saved, because once the source file has been compiled, it 
does not need to be recompiled again unless some changes have been made. The schematic 
structure of the program is shown in FIG^ Note that in order to let the make command 
work smoothly, especially, to deal with some preprocessor parameters in the source files, all 
the suffixes of the source files (with suffix .for) in the original version of BCVEGPY2.0 [2] 
are renamed as .F and the suffixes of the original header files (with suffix .f) are renamed 
as .h. 

(2) To simulate the events in mixture of the Be and its excited states properly and in 
order to save CPU time, we offer an additional option in the package BCVEGPY2.1: 
by setting 1VEGASOPEN=0 and 1GRADE=1, one may generate the mixed Be events 
just by reading the existent importance sampling function and total cross-section from 
'previous' VEGAS runs for the production, when they have been saved in date files with 
initmixgrade.F accordingly. Thus it means that when using the package with this option, 
one runs VEGAS only once. Whereas, in BCVEGPY2.0 j^, there is only one option 
by setting IVEGAS0PEN=1: it is to run VEGAS every time, although the importance 
sampling function obtained by each run is recorded in an existed grade file in the data 
subdirectory. For the new option offered here, the trick to save CPU time is not to run 



1 The first version BCVEGPYl.O has already been introduced into ATHENA 111, Isl and SIMUB 9], and 
the import of BCVEGPY2.1 into LHCb package Gauss is in progress ,10j . 



VEGAS, once the importance sampling function has been recorded in the .grid file already. 

(3) In the package BCVEGPY2.1, for testing the importance sampling function obtained 
by VEGAS and simulating the true situation as well as possible, we have further offered 
another option: with setting IVEGASOPEN=0 and IGRADE=0, VEGAS or the impor- 
tance sampling function (grade function) generated in previous runs will not be used at 
all. In this case, being different from the other options, all of the files with suffix .grid 
must be generated and saved via previous run(s) for the states which one would like 
to mix according to their weights. Namely one should have them in advance, because 
the program needs to read the total cross-sections of these states from the .grid files ac- 
cordingly, so as to determine the relative weight of each state in making the mixing correctly. 



(4) As stated in Ref.j2], the precision of the generated importance sampling function by 
running VEGAS can be improved by properly adjusting the maximum iteration number, 
the number of calls to the integrand in each iteration, and the number of bins (number 
of sub- intervals dividing the [0,1] interval) as well. In the present version, we define three 
overall parameters: NVEGITMX, NVEGCALL and NVEGBIN in the head file invegas.h, 
with these three parameters one can easily adjust them. Similarly, for convenience, the 
parameters which are not changed frequently are also defined in the source file run.F, e.g. 
NUMOFEVENTS (number of events to be generated), ENERGYOFTEVA (TEVATRON 
energy) and ENERGYOFLHC (LEG energy). 

(5) All the files containing the results are put in the subdirectory data. For clarity, in 
recording the obtained data, all of the grade files are ended with the suffix .grid, all 
the intermediate files, that record the used parameter values and the VEGAS running 
information, are ended with suffix .cs and all the files that record the differential distri- 
butions, e.g. the transverse momentum and rapidity distributions of the (c6)-quarkonium, 
are ended with suffix .dat. In a specific grade file, not only the information for the 
sampling importance function is recorded, but also the total cross-section and the maximum 
differential cross-section are recorded. 

(6) A simple script, named as do which does all the necessary jobs for generating the 



events, is put in the main code directory. For convenience, a script, named as pnuglot ^ 
that may produce a high-quahty plot in Encapsulatetd PostScript (EPS) format from a 

n 

data file, is supplied here (taken from the FormCalc package |2]). 



(7) We have found several typos in BCVEGPY2.0 2], so we list all of them and their 
corrections here: 

• In the subprogram bcvegpy.for: in line 493-507, the values for MSTU(112) 
and PARU(112) should be exchanged; in line 212, IMIXTYPE=1 should be re- 
placed by IMIXTYPE=3; in line 956, PETA=PYP(I,19) should be replaced with 
PSETA=PYP(I,19). 

• In the subprogram genevnt.for: in line 505, ICOLUP(1,3)=503 should be replaced by 
ICOLUP(1,4)=503. 

• In the subprogram parameter. for: we should add the statement 'double complex col- 
mat, bundamp' for assigning the nature of the variables in all of the three subroutines 
there; in the subroutine setparameter when calling the subroutine setctq6, to match 
to the default setting of the parameters, the original setctq6(3) should be replaced by 
setctq6(4), which corresponds to the default setting of PDF as CTEQ6L1 p. 
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